<h1>Use Cases and Requirements for Element Queries</h1>

<pre class='metadata'>
Group: wicg
Status: ED
ED: https://github.com/WICG/cq-usecases
Shortname: cq-usecases
Level: 1
Editor: Tommy Hodgins, WICG, https://wicg.io
Former Editor: Mat Marquis, RICG, http://responsiveimages.org
Former Editor: Scott Jehl, Filament Group, http://filamentgroup.com
Abstract: This document captures the use cases and requirements for standardizing a solution for element queries. The <a href="#usecases">use cases</a> and <a href="#dfn-requirements">requirements</a> are currently being gathered with consultation with <abbr title="Web Platform Incubator Community Group">WICG</abbr></a> group members, and the general public.
!Version History: <a href="https://github.com/WICG/cq-usecases/gh-pages">Commit History</a>
!Participate: <a href="irc://irc.w3.org:6665/#wicg">IRC: #wicg on W3C's IRC</a>
!Participate: <a href="https://github.com/WICG/cq-usecases">GitHub</a>
</pre>

<style>
[data-link-type=element] { font-family: monospace; }
[data-link-type=element]::before { content: "<" }
[data-link-type=element]::after { content: ">" }
img { max-width: 100%; }
</style>

<div boilerplate="status">
This is an unofficial draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.
</div>

<h2 id="intro">Introduction</h2>

Given a complex responsive layout, developers often require granular control over how the contents of an individual module will respond relative to the size of their parent container rather than the viewport size. This limitation conflicts with the goal of creating modular, independent components, often requiring a number of redundant CSS, complex exception cases, and workarounds, and the problem compounds itself depending on how dramatically a module adapts at each of its breakpoints.

For the purposes of this document, an <dfn id="dfn-element-query">element query</dfn> refers not to a specific syntax or proposed method of addressing the use cases that follow, but a method of controlling styling based on the size of a containing element.

This document presents some of the use cases that “element queries” would solve, in allowing authors to define styles (chiefly, layouts) within an individual module on the basis of the size of the module itself rather than the viewport. The goal is to demonstrate, beyond a reasonable doubt, the need for a standardized method of allowing content to respond to its container’s dimensions (as opposed to the overall viewport size). This would facilitate the construction of layouts comprised of many modular, independent HTML components with a minimum of duplicated CSS and overrides specific to the modules’ parent containers.

In formulating the requirements, this document tries to be neutral—it is not predicated on any solution. The document only tries to describe the use cases and what the WICG understands, from practice, would be needed to address the use cases in the form of requirements. The WICG expect that a technical specification can be created to formally address each or all of the requirements (i.e., the <dfn id="dfn-solution">solution</dfn>).

<h2 id="usecases">Use Cases</h2>

This document reflects the efforts of members from the <a href="http://www.w3.org/community/respimg/">Responsive Issues Community Group</a> (RICG) and <a href="https://wicg.io">Web Platform Incubator Community Group</a> (WICG), and with ongoing feedback from the designer/developer community via blog posts, informal polls, and other social media sources. The WICG's goal for this document is to make sure that developer requirements for element queries have been captured for the purpose of standardization.

The following <dfn id="dfn-usecases">use cases</dfn> represent common usage scenarios:

<a href="#fig-1">Figure 1</a> is an example of a relatively simple and fully self-contained module’s layout, using only a single <code>min-width</code> <a href="http://dev.w3.org/csswg/mediaqueries-4/#media-query">media query</a> to reflow content.

<figure id="fig-1">
	<img src="images/module-layout2.gif">
	<figcaption>An example of a self-contained module that requires a single breakpoint.</figcaption>
</figure>

In this layout, this module can occupy containing elements of varying widths, governed by multiple breakpoints. In small viewports, we’ll be using a linear layout where each of our five modules occupy the full viewport — this layout is covered by the base styles outside of our <a href="http://dev.w3.org/csswg/mediaqueries-4/#media-query">media query</a>. At higher breakpoints, these modules will be displayed side-by-side: three across, then below that two across. The three-across layout will be covered by the global styles within our viewport-based media query. Parent-specific overrides will need to be written for the two-across layout, as these modules will need to shift to their wide-format at a smaller viewport size than the ones above them.

<figure id="fig-2">
	<img src="images/eq-layout1-modules.gif">
	<figcaption>Some of the contexts in which the module in <a href="#fig-1">fig. 1</a> might appear.</figcaption>
</figure>

In order to accomplish this layout, a developer would need to duplicate all of this module’s “wide layout” styles into a second viewport-based media query—set to apply at a smaller min-width than the global breakpoint styles—with all of our styles scoped to a parent container. This now means that any future edits or bug fixes to the wide-format layout styles will need to be made in multiple places, and this maintenance cost increases exponentially with each module-level breakpoint required.

<figure id="fig-3">
	<img src="images/eq-heatmap1.gif">
	<figcaption>A stylesheet heatmap showing the redundant styles required to accomodate the layout variations in <a href="#fig-2">fig. 2</a> </figcaption>
</figure>

Similarly, introducing a new context unlike the previous two—shown in <a href="#fig-4">figure 4</a> with the introduction of a “sidebar” on an interior page layout—means duplicating or overriding all of a module’s media queries yet again.

<figure id="fig-4">
	<img src="images/eq-layout2-modules.gif">
	<figcaption>A wireframe introducing a new context for the modules in <a href="#fig-1">fig. 1</a>, where no breakpoint should apply</figcaption>
</figure>

The module in this new sidebar context will never need to reflow to the wider layout, and as such we’re left with two options: scoping all of our modules—with the exception of the two-across layout—to a parent class, or introducing a new media query that overrides all of our wide-layout styles based on the sidebar’s parent class. Despite the relative simplicity of our module and our overall page layouts, one is left with a bloated and difficult to maintain stylesheet.

<figure id="fig-5">
	<img src="images/eq-heatmap2.gif">
	<figcaption>A stylesheet heatmap showing added redundancy and rewriting of existing styles required to accommodate the layout variation in <a href="#fig-4">fig. 4</a> </figcaption>
</figure>

<h2 id="limitations-of-current-techniques">Limitations of current techniques</h2>

There is currently no native CSS mechanism available to developers that achieves the primary function of container queries, which is to <em>employ the full capabilities of CSS to a specific element tree based on the state and properties of their container</em>. Therefore developers must look to workarounds to achieve their goals. These workarounds and their limitations are outlined here:

<dl>
    <dt>
        Media Queries
    </dt>
    <dd>
        The use of Media Queries can only affect CSS changes based on the state and properties of the viewport. The viewport is not a good indicator of the state and properties of a particular container within the viewport.
    </dd>
    <dt>
        CSS layout methods
    </dt>
    <dd>
        CSS layout methods such as <strong>Flexbox</strong> and <strong>Grid</strong>, alongside <strong>CSS-based workarounds</strong> (such as the <a href="https://medium.freecodecamp.org/the-fab-four-technique-to-create-responsive-emails-without-media-queries-baf11fdfa848">Fab Four technique</a> which uses a combination of <code>width</code>, <code>calc</code>, <code>min-width</code> and <code>max-width</code> to affect binary changes to an elements width based on the width of its parent when compared to a static value, or 'breakpoint') can only deliver a small fraction of the functionality Container Queries are intended to offer.
        These methods cannot employ the full capabilities of CSS on an element tree. For example, they cannot affect a child element's <code>display</code> property in order to affect an new layout based on the width of a container.
    </dd>
    <dt>
        <code>iframe</code>s
    </dt>
    <dd>
        The use of <code>iframe</code>s produces the closest effect to what Container Queries is intended to achieve, but their use has some significant drawbacks:
        
        <ol>
            <li>
                Without the use of JavaScript, some browsers require that the contents of the <code>iframe</code> are stored in a <em>separate HTML document</em> rather than being part of the current document. This necessitates a new document composition paradigm that’s very different from the methods currently employed by developers.
            </li>
            <li>
                There is currently no standard, declarative way for an <code>iframe</code> to auto-size to fit its contents. A container that is the subject of a Container Query is still expected to be able to adapt to its contents in the <em>opposite</em> dimension of the query. For example, in the case of a Container Query that is based on a container's <em>width</em>, it is still expected that the container can adapt to the <em>height</em> of it's contents, subject to any overflow rules.
            </li>
            <li>
                The contents of an <code>iframe</code> do not inherit any styles from their parent document, forcing the styles used by the 'module' to be redeclared.
            </li>
            <li>
                <code>iframe</code>s incur additional overhead by creating additional nested browsing contexts, which can degrade performance.
            </li>
        </ol>
    </dd>
    <dt>
        JavaScript-based solutions
    </dt>
    <dd>
        JavaScript-based solutions (for example <a href="https://elementqueries.com/">EQCSS</a>) should not be considered an adequate replacement for a native CSS solution for all the same reasons any other layout- or appearance-based declarations are the domain of CSS, not JavaScript. The usual caveats of JavaScript availability and failure also apply.

        JavaScript solutions also create additional network traffic, require additional parsing and perform an additional reflow after every layout that affects the matching state of a container query.
    </dd>
</dl>

<h2 id="requirements">Requirements</h2>

The use cases give rise to the following <dfn id="dfn-requirements">requirements</dfn>:

<ol>
	<li>
</ol>

<h2 id="issues">Open issues</h2>

We are <a href="https://github.com/WICG/cq-usecases/issues">tracking open issues</a> on Github. Please help us close them!

<h2 id="changes">Change history</h2>

A <a href="https://github.com/WICG/cq-usecases/commits/gh-pages">complete history of changes</a> is available on Github.

You can also see all <a href="https://github.com/WICG/cq-usecases/issues?q=is%3Aclosed">closed issues</a> relating to this document.

<h2 id="acks">Acknowledgements</h2>

A <a href="https://www.w3.org/community/wicg/participants">complete list of participants</a> of the Web Platform Incubator Community Group is available at the W3C Community Group Website.
